User Defined Enterprise MIB Example Application

This application demonstrates how to add an enterprise MIB to the SNMP agent
and how to use the NETOS MIB Compiler.  This application includes files that 
were generated by the NETOS MIB compiler, using the enterprise MIB located in
.\mibs\example-mib2, and then modified to demonstrate an enterprise MIB.

The files generated by the NETOS MIB compiler have file names based on the MIB
definition name.  For instance, in the example-mib2 MIB, the definition name 
is EXAMPLE.  (See the first line in the MIB file.)  Thus when running the
the NETOS MIB Compiler on the example-mib2 MIB, the files generated are:
example_local.c, example_var.c, example_var.h, example_local.h, and 
example.ins.  The first four files are application source and header files,
and the last contains instructions for populating data structures.

Only two MIB Compiler output files require customization.  The first is the 
*_local.c file, which contains all the application specific function stubs 
needed to implement your custom enterprise MIB.  The second is the custvars.c, 
which contains data structures describing your custom enterprise MIB.  
Instructions for populating these data structures are located in the *.ins
file.

If you are interested in creating a custom enterprise MIB and understanding 
the steps needed to achieve this, Digi recommends these steps:

1.  Run this application as is, using your favorite MIB Browser.  You can 
    communicate with the target SNMP agent by performing a full SNMP MIB walk, 
    which includes the standard Internet MIB-II (defined by RFC 1213), plus 
    the enterprise MIB defined by the example-mib2 MIB.  The Internet MIB are 
    those elements at OIDs 1.3.6.1.2.1. and the namib sample enterprise MIB, 
    created using the MIB Complier, are located at 1.3.6.1.4.1.901.  The 
    hierarchy of the enterprise MIB's objects is:

            example\nsil\exampleOne\group\greenLedOn
                                         \yellowLedOn
                                         \bigBoss
            example\nsil\exampleOne\table\simpleTable\simpleEntry\index
                                                                 \name

2.  Now that you have completed executing the example application, we'd like 
    you to experience compiling a MIB and rebuilding the application using the 
    files generated by the MIB compiler.  To do so, follow the proceudure 
    below in the section "Instructions to recompile this sample's MIB".

3.  Now that you are familiar with running the MIB compiler and how the MIB
    Compiler output files link to your application code, create your own MIB 
    and add your specific application function stubs.  Update the custvars.c 
    file with instructions provided in *.ins.  Replace, as needed, the source 
    and header files needed in the build/make files.  Then compile and run 
    using your favorite MIB Browser.

    Note: When you update custvars.c, don't forget to remove the current 
    example MIB references.  In particular, the #include example_*.h, the 
    tvSnmpExampleoneVars array and it's usage in the custSnmpSubtrees array.
    
    Note: A MIB file can contain only one MIB definition.  In the case of a 
    custom MIB containing other MIBs, place these MIB files in the 
    c:\netos\mibcomp\mibcomp_win321\smi\mibs\ietf directory.

*************************************************************************
*                                                                       *
*  Instructions to recompile this sample's MIB                          *
*                                                                       *
*************************************************************************

Assuming that c:\netos is the NET+OS installation directory.

1.  Open a Windows command line window.
2.  Change directory to c:\netos\src\examples\namib
3.  Delete the NETOS MIB Compiler output files example*.*.  A copy of these 
    exist in the .\backup directory and will be used for reference later.
4.  Invoke the NETOS MIB Compiler by entering in the Windows command line:

    >mib2src .\mibs\example-mib2

    In the case of a successful compilation, the  NETOS MIB compiler genarates 
    files: example_local.c, example_local.h, example_var.c, example_var.h, 
    example.ins.  

    The file example.ins contains instructions on the changes needed to 
    integrate the user defined MIB with the SNMP agent.  For this sample 
    application, the root.c makes a call to initializeCustomMibs(), located in 
    custvars.c, which contains a call to naInitializeCustomMibs() that 
    includes the custSnmpSubtrees and custConceptualTables data structures.

    When you use your own custom enterprise MIB, the file custvars.c will 
    require updates with your specific custSnmpSubtrees, custConceptualTables 
    and tvSnmpExampleoneVars per your MIB's *.ins file.

    To rerun this example, no change is needed, since the instructions from 
    example.ins have already been integrated into the custvars.c file.

    The application specific portion of your enterprise MIB should be placed 
    in the empty function stubs created in the example_local.c file.  For 
    convenience, all the demonstration code is located in mibstubs.c.  The
    added application hooks fleshing out the stub functions can be better 
    understood by comparing the originally modified example_local.c file 
    (located in the .\backup directory) to the new one just generated.

5.  Copy the original .\backup\example_local.c to .\example_local.c. 

    Now you can recompile, link and rerun the namib sample application.

*************************************************
*                                               *
*   Next Steps                                  *
*                                               *
*************************************************

    At this point, you can modify the sample MIB or replace this MIB with your
    own MIB.  Assuming the MIB Definition name in your MIB is now called
    MibName (instead of EXAMPLE), the procedure outlined can be repeated, 
    except the files generated by the MIB Compiler will be mibname_local.c, 
    mibname_local.h, mibname_var.c, mibname_var.h, and mibname.ins.  The 
    make/build files will need to be updated to incorporate the new MIB 
    Compiler output files (and removing the old example*.* files).

    The structures in custvars.c will need modification per the mibname.ins
    file and the empty function stubs in mibname_local.c will need fleshing 
    out.  Note the comments in function headers in mibname_local.c provide 
    guidance to how the functions should be implemented.

The following files are provided in this template.

appconf.h         sets application configuration settings
.\32b\image.gpj   used to build the big endian Green Hills version of the
                  application.  The build script creates a version that
                  can be debugged with Multi, and the file image.bin 
                  which can be written into a ROM that uses the bootloader.
.\32b\makefile    Make file for the GNU toolset.
.\32b\rom.gpj     used to build the big endian ROM image of application
project.gpj       contains application specific build settings
readme            this file
root.c            contains the applicationStart() function that starts
                  the SNMP agent
custvars.c        contains custSnmpSubtrees and custConceptualTables tables, 
                  to which entries must be added from example.ins file, and 
                  the call to naInitializeCustomMibs API call.
mibstubs.c        contains application specific MIB functionality.  These 
                  functions are included and used to flesh out the raw 
                  example_local.c file.  Note that all modifications to this 
                  file are encapsulated within the NET_OS_SPECIFIC definition.
example_local.h   header file generated by the MIB compiler
example_local.c   C file generated by the MIB compiler that contains stub
                  functions for the user to fill in
example_var.h     header file generated by the MIB compiler
example_var.c     C file generated by the MIB compiler that contains code
                  calls the stub functions in example_local.c
.\backup          Contains a copy of the example_*.* files.


In addition, the following files in the BSP directory are built
as part of this application.

reset.s         contains the reset code
appconf_api.c   contains code used to read settings in appconf.h


The application build file links in the following libraries.  Most of these
libraries are not actually used by the application.  They are included because
this application is meant to be used as a template for other applications that
may use these libraries.  The linker only includes the code in libraries that 
is actually used.  For example, none of the code in the email client library 
will be linked into this application since it does not call any email APIs.

The library names are listed below.

libbsp.a           contains the BSP library
libtcpip.a         contains the TCP/IP stack library
libtx.a            contains the ThreadX kernel library
libfilesys.a       contains the file system library
libposix.a         contains the POSIX layer library
libflash.a         contains the Flash driver library
libsnmp.a          contains the SNMP library
libftpclnt.a       contains the FTP client library
libftpsvr.a        contains the FTP server library
libemailc.a        contains the Email client library
libtelnsvr.a       contains the Telnet server library
libdnsclnt.a       contains the DNS client library

The application uses the following files located in the
netos\src\linkerScripts directory.  These files are generated
when the BSP is built.

bootldr.dat     bootloader configuration file used to generate the
                file image.bin.  It controls the information placed
                in the bootloader header of the image.

image.ld        GNU linker script used to build an image that can
                be debugged and used with the bootloader.

image.lx        Green Hills linker script used to build an image
                that can be debugged and used with the bootloader.

